home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / pwfosl10.zip / PWFOSSIL.DOC < prev    next >
Text File  |  1992-04-01  |  17KB  |  490 lines
  1. PWFOSSIL
  2.  
  3. A unit designed to make FOSSIL communications easier.
  4.  
  5. Written for Turbo Pascal 6.0
  6.  
  7. by 
  8.  
  9. Jody Burrow
  10.  
  11. Patchwork Software Development
  12. Copyright Notice
  13. ----------------
  14.  
  15. This document and all included programs and files are Copyright
  16. (c) 1992 by Patchwork Software Development.  All rights are
  17. hereby reserved.
  18.  
  19.  
  20. Trademark Acknowledgements
  21. --------------------------
  22.  
  23. Turbo Pascal is a registered trademark of Borland International.
  24.  
  25. IBM PC/XT/AT and PC-DOS are registered trademarks of
  26. International Business Machines.
  27.  
  28. MS-DOS is a registered trademark of Microsoft, Inc.
  29.  
  30. X00.SYS is a trademark of Raymond L. Gwinn.
  31.  
  32. BNU.COM is a trademark of David Nugent and Unique Computing Pty
  33. Ltd.
  34.  
  35.  
  36. Table of Contents
  37. -----------------
  38.  
  39. Copyright Notice . . . . . . . . . . . . . . . . . . . . . . . ii
  40.  
  41. Trademark Acknowledgements . . . . . . . . . . . . . . . . . . ii
  42.  
  43. Table of Contents. . . . . . . . . . . . . . . . . . . . . . .iii
  44.  
  45. Registration . . . . . . . . . . . . . . . . . . . . . . . . . iv
  46.  
  47. Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  1
  48.  
  49. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
  50.      CarrierDetect . . . . . . . . . . . . . . . . . . . . . .  2
  51.      DeInitFossil. . . . . . . . . . . . . . . . . . . . . . .  3
  52.      DTRRaise. . . . . . . . . . . . . . . . . . . . . . . . .  4
  53.      FlushOutput . . . . . . . . . . . . . . . . . . . . . . .  5
  54.      InitFossil. . . . . . . . . . . . . . . . . . . . . . . .  6
  55.      InputCheck. . . . . . . . . . . . . . . . . . . . . . . .  7
  56.      PurgeInput. . . . . . . . . . . . . . . . . . . . . . . .  8
  57.      PurgeOutput . . . . . . . . . . . . . . . . . . . . . . .  9
  58.      Reboot. . . . . . . . . . . . . . . . . . . . . . . . . . 10
  59.      RecvChar. . . . . . . . . . . . . . . . . . . . . . . . . 11
  60.      SetBaud . . . . . . . . . . . . . . . . . . . . . . . . . 12
  61.      SetFlowControl. . . . . . . . . . . . . . . . . . . . . . 13
  62.      SetWatch. . . . . . . . . . . . . . . . . . . . . . . . . 14
  63.      SendChar. . . . . . . . . . . . . . . . . . . . . . . . . 15
  64.      SendString. . . . . . . . . . . . . . . . . . . . . . . . 16
  65. Registration
  66. ------------
  67.  
  68. PWFOSSIL is a shareware product.  This means that you are
  69. required to register it with the author if you are still using it
  70. after a trial period of 30 days.  You may not distribute software
  71. written with it without registering the product.  A short message
  72. will be shown on the screen upon initialization of the unit. 
  73. Registering will remove this message as well as entitling you to
  74. receive the source code for this unit.  
  75.  
  76. This program is provided "AS IS" without any kind of warranty. 
  77. Please note that Patchwork Software development is not
  78. responsible for any damages this program causes and that you
  79. assume all responsibility for the use of this program.  The
  80. entire risk of quality, suitability, and performance is left up
  81. to you, the user.  
  82.  
  83. Registration is a very minimal fee for this product.  It is only
  84. $7.50 for 5.25" disks and $10.00 for 3.5" disks.  To register,
  85. send a check made out to Jody Burrow and the completed
  86. REGISTER.FRM in the distribution package to the following
  87. address:
  88.  
  89.                     Jody Burrow
  90.                     Patchwork Software Development
  91.                     1611 E. Lark
  92.                     Springfield, MO
  93.                     65804-4351
  94.  
  95. You will receive your registered copy and source code in the US
  96. Mail within 2 weeks.
  97.  
  98. With any software you create with the registered copy, you are
  99. free to distribute it however you choose.  We request however
  100. that somewhere either on the title screen of the program or in
  101. the documentation you put in the following line:
  102.  
  103. FOSSIL routines provided by Patchwork Software's PWFOSSIL Introduction
  104. ------------
  105.  
  106. Patchwork FOSSIL Interface (PWFOSSIL) is a unit written for Turbo
  107. Pascal 6.0 developed for the purpose of easing the use of FOSSIL
  108. drivers such as BNU.COM or X00.SYS.  Communication programs often
  109. use these routines to communicate with devices such as modems.  I
  110. created this unit to ease my development of some software which
  111. heavily accessed the communication ports on my PC.  
  112.  
  113. To use this unit requires the following:
  114.  
  115.      * IBM PC/XT/AT or compatible machine running MS or PC-DOS
  116.      * Turbo Pascal 6.0 (earlier versions will not work!)
  117.      * A FOSSIL driver (X00.SYS and BNU.COM are good ones)
  118.  
  119. The following pages will go into detail describing each command
  120. written in this unit.  The format will be as follows:
  121.  
  122.      Name:*******************
  123.  
  124.      Type:*******************
  125.  
  126.      Syntax:*****************
  127.  
  128.      Returns:****************
  129.  
  130.      Description:************
  131.  
  132.      Example:****************
  133.  
  134. Examples will be given on each command to aid the user in fully
  135. understanding the command.
  136.  
  137. All commands are listed in alphabetical order.  In no way does
  138. this imply that this is the order in which you must call them.
  139.  
  140. If there are any questions concerning this unit, you may reach me
  141. by phone at 1-417-881-5097, by FidoNET net-mail at 1/284:13, or
  142. by mail at the address listed in the registration section. 
  143.  
  144. Hope you enjoy this unit, and please don't forget to register. 
  145. Registration will help aid the development of other great
  146. products from Patchwork Software Development.
  147.  
  148. Commands
  149. --------
  150.  
  151.        Name: CarrierDetect
  152.  
  153.        Type: Function
  154.  
  155.      Syntax: CarrierDetect(port: integer);
  156.                port = COM port number
  157.  
  158.     Returns: boolean variable 
  159.                  TRUE = Carrier is detected  
  160.                 FALSE = NO Carrier is detected  
  161.  
  162. Description: This function tells whether or not the modem shows   
  163.              that carrier is detected.  It returns the state of   
  164.              the carrier as a boolean variable.  You must pass    
  165.              the function your COM port number as an integer      
  166.              type, i.e. COM1 is 1, COM2 is 2, etc.
  167.  
  168.     Example: var
  169.                result: boolean
  170.              begin
  171.                result:=CarrierDetect(1);
  172.                if result=TRUE then 
  173.                  writeln('Carrier is detected)
  174.                else
  175.                  writeln('Carrier is NOT detected);
  176.              end.
  177.        Name: DeInitFossil
  178.  
  179.        Type: procedure
  180.  
  181.      Syntax: DeInitFossil(port: integer);
  182.                port = COM port number
  183.  
  184.     Returns: none
  185.  
  186. Description: This is used to end all communication functions with 
  187.              the driver.  When you are finished using the FOSSIL  
  188.              driver, it is recommended that you call this         
  189.              function.  Please note that DTR is not affected by   
  190.              this call.
  191.  
  192.     Example: begin
  193.                DeInitFossil(1);
  194.                Writeln('FOSSIL is now closed!');
  195.              end.
  196.        Name: DTRRaise
  197.  
  198.        Type: procedure
  199.  
  200.      Syntax: DTRRaise(port: integer; raise: boolean);
  201.                port = COM port number
  202.                raise = DTR state desired
  203.  
  204.     Returns: none
  205.  
  206. Description: This procedure changes the state of the modem's DTR  
  207.              line.  Passing a FALSE in the raise parameter lowers 
  208.              DTR and disables the modem.  Passing a TRUE in the   
  209.              raise parameter raises DTR and enables the modem.    
  210.              This procedure is useful for hanging up the modem.
  211.  
  212.     Example: begin
  213.                DTRRaise(1,TRUE);
  214.                Writeln('The modem is enabled!');
  215.                DTRRaise(1,FALSE);
  216.                Writeln('The modem is disabled!');
  217.              end.
  218.        Name: FlushOutput
  219.  
  220.        Type: procedure
  221.  
  222.      Syntax: FlushOutput(port: integer);
  223.                port = COM port number
  224.      
  225.     Returns: none
  226.  
  227. Description: This procedure takes all output in the               
  228.              communications buffer and forces it to be sent out.  
  229.              Note that using this routine with flow control can   
  230.              cause your machine to hang under certain             
  231.              circumstances.  
  232.  
  233.     Example: begin
  234.                FlushOutput(1);
  235.                Writeln('All output has been flushed!');
  236.              end;
  237.        Name: InitFossil
  238.  
  239.        Type: function
  240.  
  241.      Syntax: InitFossil(port: integer);
  242.                port = COM port number
  243.  
  244.     Returns: success: boolean
  245.  
  246. Description: This routine must be called before any other FOSSIL
  247.              related routines in this unit are called.  This      
  248.              opens the FOSSIL driver for the specified port.  It  
  249.              returns a boolean value determining the success of   
  250.              the opening operation.  TRUE is returned if          
  251.              successful, FALSE is returned if unsuccessful.
  252.  
  253.     Example: var
  254.                success: boolean
  255.              begin
  256.                success:= InitFossil(1);
  257.                If success = TRUE
  258.                  writeln('FOSSIL opened successfully!')
  259.                else
  260.                  writeln('FOSSIL not opened successfully!');
  261.              end.
  262.        Name: InputCheck
  263.  
  264.        Type: function
  265.  
  266.      Syntax: InputCheck(port: integer);
  267.                port = COM port number
  268.  
  269.     Returns: available: boolean
  270.  
  271. Description: This function checks whether or not characters are   
  272.              available in the communications input buffer.  If    
  273.              characters are available, the function returns TRUE  
  274.              as a boolean.  Otherwise it returns a FALSE.
  275.  
  276.     Example: var
  277.               available: boolean
  278.              begin
  279.                available: InputCheck(1);
  280.                if available:= TRUE then
  281.                  writeln('Characters are available!')
  282.                else
  283.                  writeln('No characters are available!');
  284.              end.
  285.        Name: PurgeInput
  286.  
  287.        Type: procedure
  288.  
  289.     Returns: none
  290.  
  291.      Syntax: PurgeInput(port: integer);
  292.                port = COM port number
  293.  
  294. Description: This procedure removes all pending data from the     
  295.              communication input buffer which effectively clears  
  296.              it.
  297.  
  298.     Example: begin
  299.                PurgeInput(1);
  300.                writeln('All input data has been cleared!');
  301.              end.
  302.        Name: PurgeOutput
  303.  
  304.        Type: procedure
  305.  
  306.     Returns: none
  307.  
  308.      Syntax: PurgeOutput(port: integer);
  309.                port = COM port number
  310.  
  311. Description: This operates similar to the PurgeInput routine      
  312.              except that it clears the output buffer.  Note that  
  313.              the data in the output buffer is not sent before the 
  314.              clear!
  315.  
  316.     Example: begin
  317.                PurgeOutput(1);
  318.                writeln('No output data is left in the buffer!');
  319.              end.
  320.  
  321.        Name: Reboot
  322.  
  323.        Type: procedure
  324.  
  325.     Returns: none
  326.  
  327.      Syntax: Reboot(type: boolean);
  328.                type = Type of reboot
  329.                     TRUE = warm boot
  330.                     FALSE = cold boot
  331.  
  332. Description: Using this procedure will cause a total reboot of    
  333.              your system.  It will either perform a warm reboot,  
  334.              or a cold reboot which will start the system from    
  335.              scratch.  Use this procedure with caution.
  336.  
  337.     Example: begin
  338.                writeln('A warm reboot will occur!');
  339.                Reboot(TRUE);
  340.              end.
  341.  
  342.              - or -
  343.  
  344.              begin
  345.                writeln('A cold reboot will occur!');
  346.                reboot(FALSE);
  347.              end.
  348.        Name: RecvChar
  349.  
  350.        Type: function
  351.  
  352.     Returns: status: boolean
  353.                TRUE = characters available
  354.               FALSE = characters not available
  355.  
  356.      Syntax: RecvChar(port: integer; var charrecv: char)
  357.                port = COM port number
  358.                charrecv = character received from buffer
  359.     
  360. Description: This routine gets characters from the FOSSIL's input 
  361.              buffer.  The character is placed in the character    
  362.              type variable passed by you to the function in the   
  363.              parameter section.  The function returns a variable  
  364.              which states whether or not characters are available 
  365.              to be received.
  366.  
  367.     Example: var
  368.                status: boolean;
  369.                ch: char;
  370.              begin
  371.                status:= RecvChar(1, ch);
  372.                if status=TRUE then Writeln('The character         
  373.                                             received is '; ch)
  374.                else writeln('No character available!');
  375.              end.
  376.        Name: SetBaud
  377.  
  378.        Type: procedure
  379.  
  380.      Syntax: SetBaud(baud: word; port, stopbit, charlen: integer; 
  381.                      p: parity);
  382.                baud = baud rate of port (300, 600, 1200, 2400,    
  383.                                          4800, 9600, 19200, 38400 
  384.                                          supported)
  385.                port = COM port number
  386.                stopbit = number of stop bits (1 and 2 supported)
  387.                charlen = character length (5, 6, 7, 8 supported)  
  388.                parity = type of parity (none, even, odd           
  389.                                         supported)
  390.    
  391.     Returns: none
  392.  
  393. Description: This procedure sets the baud rate and other          
  394.              communications parameters required of the FOSSIL.    
  395.              If invalid parameters are passed to the procedure,   
  396.              it will print an error message and end the program   
  397.              entirely, therefore make sure the parameters you     
  398.              send are correct!
  399.  
  400.     Example: begin
  401.                SetBaud(2400, 1, 1, 8, none);
  402.                Writeln('This sets COM1: for 2400,N,8,1!');
  403.              end;
  404.        Name: SetFlowControl
  405.  
  406.        Type: procedure
  407.  
  408.      Syntax: SetFlowControl(port: integer, STran, Hard, SRecv:    
  409.                             boolean);
  410.  
  411.                port = COM port number
  412.                STran = XON/XOFF software on transmit only
  413.                Hard = CTS/RTS hardware
  414.                SRecv = XON/XOFF software on receive only
  415.                  TRUE turns it on   ->  on above
  416.                  FALSE turns it off -> three only
  417.  
  418.     Returns: none
  419.  
  420. Description: This sets the type(s) of flow control that the       
  421.              FOSSIL and the communications port will use.  Most   
  422.              high speed communications will require some type to  
  423.              be used depending on the application.  Consult your  
  424.              modem's documentation for more information on flow   
  425.              control.
  426.   
  427.     Example: begin
  428.                SetFlowControl(1, TRUE, FALSE, TRUE);
  429.                writeln('only software flow control is on!');
  430.              end.
  431.        Name: SetWatch
  432.  
  433.        Type: procedure
  434.  
  435.      Syntax: SetWatch(port: integer; state: boolean);
  436.                port = COM port number
  437.                state = state of carrier watchdog
  438.                  TRUE = on
  439.                  FALSE = off
  440.  
  441.     Returns: none
  442.  
  443. Description: This procedure turns on and off the carrier          
  444.              watchdog.  With it on, the system will reboot when   
  445.              carrier is lost no matter what. Passing a TRUE in    
  446.              the state parameter turns it on, FALSE turns it off.
  447.      
  448.     Example: begin
  449.                SetWatch(1, TRUE);
  450.                writeln('Watchdog is on!');
  451.                SetWatch(1,FALSE);
  452.                writeln('Watchdog is off!');
  453.              end.
  454.        Name: SendChar
  455.  
  456.        Type: procedure
  457.  
  458.      Syntax: SendChar(port: integer; ch: char);
  459.  
  460.     Returns: none
  461.  
  462. Description: This procedure sends a character to the specified    
  463.              communications port.  Nothing is added to the        
  464.              character, it is sent just as given.
  465.  
  466.     Example: begin
  467.                SendChar(1, 'C');
  468.                Writeln ('The character C was sent.');
  469.              end.
  470.        Name: SendString
  471.                                                                  
  472.        Type: procedure
  473.  
  474.      Syntax: SendString(port: integer; st: string);
  475.  
  476.     Returns: none
  477.  
  478. Description: This procedure sends a string to the specified       
  479.              communications port.  The string can be a maximum of 
  480.              255 characters long (a pascal limit).  No            
  481.              translation is made or other characters are added to 
  482.              the string, It is sent as given.
  483.  
  484.     Example: begin
  485.                SendString(1, 'Hello!');
  486.                writeln('The string Hello! was sent.');
  487.              end;
  488.  
  489.                            
  490.